Deploying Eggplant IAM with Docker

This page describes how to deploy Keycloak in a Docker container. Before proceeding with the steps on this page, be sure to complete the pre-deployment steps for Windows or Linux.

Prepare environment

note

You can copy the command examples in this document by hovering over the right-side of the example to display a Copy button and then clicking it.

1. Ensure that your TLS certificate and key are saved in pem format in separate files.

2. Create a file called .env in the same folder as the Docker Compose file with the content below, updating the values to suit your installation:

   KC_ADMIN_USER=admin
   KC_ADMIN_PASSWORD=securepassword1
   KEYCLOAK_URL=https://iam.example.com
   REALM_INSTALLER_CLIENT_SECRET=realm_installer_client_secret 
   
   INITIAL_USER_USERNAME=username
   INITIAL_USER_PASSWORD=securepassword2
   INITIAL_USER_GIVEN_NAME=given_name
   INITIAL_USER_FAMILY_NAME=family_name
   INITIAL_USER_EMAIL=email_address
   
   TLS_CERT=/path/to/tls.crt
   TLS_KEY=/path/to/tls.key
   Important

   The INITIAL_USER_PASSWORD value, shown as securepassword2 above, must be at least 12 characters long.

3. If you would like to use an external PostgreSQL database then add the following to the file, updating the values for your installation:

   POSTGRES_HOSTNAME=hostname
   POSTGRES_PORT=5432
   POSTGRES_DB=postgres
   POSTGRES_USER=postgres
   POSTGRES_PASSWORD=password

Deploy Eggplant IAM with Docker

1. Download an Eggplant IAM Docker Compose file here.

2. Start Eggplant IAM by running the following command:

   docker compose --file docker-compose-6.3.247.yml --profile default up -d

   Example output:

   [+] Running 1/1
   [+] Running 6/6loak_backend_network   Created                            0.1s
    ✔ Network keycloak_backend_network   Created                            0.1s
    ✔ Network keycloak_frontend_network  Created                            0.1s
    ✔ Volume "keycloak_kc-db-data"       Created                            0.0s
    ✔ Container postgres                 Healthy                            0.0s
    ✔ Container keycloak-server          Healthy                            0.0s
    ✔ Container nginx                    Started

3. Run the realm provisoner to add the Eggplant specfic configuration to the installation:

   docker compose --file docker-compose-6.3.247.yml --profile realm-config up

   Example output:

   [+] Running 1/0
    ✔ Container kc-realm-config-installer  Created                          0.0s
   Attaching to kc-realm-config-installer
   kc-realm-config-installer  | inclusions: /config/00_shared/*.yaml
   kc-realm-config-installer  | import_locs: /config/00_shared/*.yaml,
   kc-realm-config-installer  | 2025-04-15T16:33:44.905Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigApplication   : Starting KeycloakConfigApplication v6.4.0 using Java 21.0.6 with PID 8 (/app/keycloak-config-cli.jar started by nobody in /)
   kc-realm-config-installer  | 2025-04-15T16:33:44.908Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigApplication   : No active profile set, falling back to 1 default profile: "default"
   kc-realm-config-installer  | 2025-04-15T16:33:45.362Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigApplication   : Started KeycloakConfigApplication in 0.789 seconds (process running for 1.173)
   kc-realm-config-installer  | 2025-04-15T16:33:45.838Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/00_shared/01_master_realm.yaml'
   kc-realm-config-installer  | 2025-04-15T16:33:47.005Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/00_shared/02_shared_realm.yaml'
   kc-realm-config-installer  | 2025-04-15T16:33:48.544Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/00_shared/03_shared_client_scopes.yaml'
   kc-realm-config-installer  | 2025-04-15T16:33:48.856Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/00_shared/04_shared_client.yaml'
   kc-realm-config-installer  | 2025-04-15T16:33:49.196Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/00_shared/05_shared_client_roles.yaml'
   kc-realm-config-installer  | 2025-04-15T16:33:50.352Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/00_shared/06_shared_roles.yaml'
   kc-realm-config-installer  | 2025-04-15T16:33:50.914Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigRunner        : keycloak-config-cli ran in 00:05.243.
   kc-realm-config-installer exited with code 0
   info

   Other useful Docker commands:

   • docker-compose --profile name logs shows logs from all containers

   • docker logs container_name shows logs from selected container

   • docker-compose --profile name stop to stop running containers.

   • docker-compose --profile name down to tear down all deployed resources

Backup and Restore

You must regularly back up configuration and results data from your IAM installation. Data that needs to be backed up is stored in PostgreSQL.

How you back up this data will depend on how you've configured your deployment, but here we provide an example of data can be backed up when using the default installation shown at the start of this document.

Backup data

1. Generate a backup of the Keycloak database and output it to a file named keycloak.dump using the following command.

   docker exec -i \
     $(docker ps \
       --filter label=com.docker.compose.project=keycloak \
       --filter label=com.docker.compose.service=postgres \
       --format '{{.ID}}') \
     sh -c 'export PGPASSWORD=$POSTGRES_PASSWORD && pg_dump --username postgres -d keycloak --clean --create' \
     > keycloak.dump

Restore data

Important

The commands below assume you generated the keycloak.dump file as part of the backup step above in your working directory.

1. Stop services to clear the database connections.

   docker ps \
     --filter label=com.docker.compose.project=keycloak \
     --format '{{.ID}} {{.Label "com.docker.compose.service"}}' \
   | awk '$2 != "postgres" {print $1}' \
   | xargs -r docker stop
   

2. Restore the keycloak database.

   docker exec -i \
     $(docker ps \
       --filter label=com.docker.compose.project=keycloak \
       --filter label=com.docker.compose.service=postgres \
       --format '{{.ID}}') \
     sh -c 'export PGPASSWORD=$POSTGRES_PASSWORD && psql --username=postgres --dbname=postgres --file=-' \
     < keycloak.dump

3. Bring the service back up by rerunning the docker compose up command for Eggplant IAM (Keycloak).

   tip

   The commands below must be run from the directories where you originally downloaded the Docker Compose file and configured the .env file.

   docker compose --file docker-compose-6.3.247.yml --profile default up -d

Upgrade IAM in Docker Deployments

info

Unless stated otherwise, the general procedure for upgrading is to preserve the existing installation and deploy using a new Docker Compose file.

Each release may have specific additional steps. So before applying this procedure, please review the notes below for the upgrade you're performing.

Upgrading 6.3.203 to 6.3.247

1. Perform a backup of the Eggplant IAM data.

2. Download the Eggplant IAM Docker Compose file here.

3. Upgrade Eggplant IAM by running the following command:

   docker compose --file docker-compose-6.3.247.yml --profile default up -d

Uninstalling

You can uninstall by running the command below.

docker compose --file docker-compose-6.3.247.yml --profile default --profile realm-config down --volumes